home *** CD-ROM | disk | FTP | other *** search
/ Workbench Add-On / Workbench Add-On - Volume 1.iso / BBS-Archive / Dev / Obrn-A_1.6_bin.lha / oberon-a / docs.lha / docs / Obrn-A_rexx.doc < prev    next >
Text File  |  1995-07-02  |  9KB  |  232 lines
  1.  
  2.      $RCSfile: Obrn-A_rexx.doc $
  3.  
  4.    Created by: fjc (Frank Copeland)
  5.     $Revision: 1.1 $
  6.       $Author: fjc $
  7.         $Date: 1995/01/25 23:38:33 $
  8.   ________________________________________________________________________
  9.  
  10.  
  11.   This archive contains several scripts written in ARexx and the AmokEd
  12.   command language. They allow the programmer to call the compiler,
  13.   pre-linker and linker from within the AmokEd editor, and to insert
  14.   error messages directly into the source code. They are intended to be a
  15.   demonstration, hopefully inspiring others to improve them and to adapt
  16.   them for use with other editors. At present the error messages only
  17.   indicate an error number and a position.
  18.  
  19.   Installation
  20.  
  21.   The files in the rexx directory should be copied to your REXX:
  22.   directory. The macros/Oberon-A.aedrc file should be copied to wherever
  23.   you keep your AmokEd macro files. Add the following line to your normal
  24.   startup file:
  25.  
  26.       'source Oberon-A.aedrc'
  27.  
  28.   The ARexx scripts require RexxDosSupport.library to access environment
  29.   variables. This can be found on AmiNet in:
  30.  
  31.       'util/rexx/RexxDosSupport14.lha'
  32.  
  33.   Usage
  34.  
  35.   The Oberon-A.aedrc file sets up a menu called 'Oberon' and creates a
  36.   number of new key bindings.  The menu items are:
  37.  
  38.     'Main module' (bound to CTRL-ALT-m)
  39.  
  40.       This is a toggle item.  It indicates whether the module is a main
  41.       program module. If it is not selected, the pre-linker and linker
  42.       menu items are disabled.
  43.  
  44.     'Library module' (bound to CTRL-ALT-l)
  45.  
  46.       This is a toggle item.  If selected, it indicates that the module
  47.       is a library module and that it's symbol and object files should be
  48.       output to 'OLIB:'. Otherwise, the files are output to the 'Code'
  49.       sub-directory.
  50.  
  51.     The above two items are mutually exclusive.
  52.  
  53.     'Compiler options' (bound to ALT-F1)
  54.  
  55.       This allows the programmer to directly edit the command line
  56.       arguments to be passed to the compiler. The DEBUG and NEWSYMFILE
  57.       arguments should not be specified (see below).
  58.  
  59.     'New symbol file' (bound to CTRL-ALT-n)
  60.  
  61.       This is a toggle item.  If selected, the NEWSYMFILE option is added
  62.       to the arguments passed to the compiler.
  63.  
  64.     'Debug symbols' (bound to CTRL-ALT-d)
  65.  
  66.       This is a toggle item.  If selected, the DEBUG option is added to
  67.       the arguments passed to the compiler.
  68.  
  69.     'Pre-linker options' (bound to ALT-F2)
  70.  
  71.       This allows the programmer to directly edit the command line
  72.       arguments to be passed to the pre-linker.
  73.  
  74.     'Linker options' (bound to ALT-F3)
  75.  
  76.       This allows the programmer to directly edit the command line
  77.       arguments to be passed to the linker.
  78.  
  79.     'Compile' (bound to F1)
  80.  
  81.       This calls the 'DoOC.rexx' script to compile the file in the active
  82.       window. The file is saved first and if any errors are detected the
  83.       'ReadErr.aed' script is called to produce error reports (see
  84.         below).
  85.  
  86.     'Pre-link' (bound to F2)
  87.  
  88.       This calls the 'DoOL.rexx' script to pre-link the module in the
  89.       active window.  This option is only active if the 'Main module'
  90.       item is selected (see above).
  91.  
  92.     'Link' (bound to F3)
  93.  
  94.       This calls the 'DoLink.rexx' script to link the module in the
  95.       active window.  This option is only active if the 'Main module'
  96.       item is selected (see above).
  97.  
  98.     'Run' (bound to F4)
  99.  
  100.       This runs the program, assuming that the current module is the main
  101.       program module. This option is only active if the 'Main module'
  102.       item is selected (see above).
  103.  
  104.     'Read Errors' (bound to F6)
  105.  
  106.       This calls the 'ReadErr.aed' script to generate a report of any
  107.       compilation errors reported for the module in the active window.
  108.  
  109.       If the default binary error file is produced by the compiler, the
  110.       script calls OEL to generate the error report. The output is
  111.       redirected to a temporary file and the file is then displayed in a
  112.       new window.
  113.  
  114.       If the TEXTERR option is used with the compiler, the script instead
  115.       inserts error reports directly into the the active window. Each
  116.       error report consists of a seperate line of the form:
  117.  
  118.         ^-- err: xxx
  119.  
  120.       This line will be inserted below the line in which the error
  121.       occurs. The caret ('^') indicates the location of the error in the
  122.       line above. The meaning of the error number can be found in the
  123.       file 'OBERON-A:Docs/ErrorCodes.doc'.
  124.  
  125.       If using the TEXTERR option, be careful not to call this script
  126.       more than once. The second call will insert error reports in the
  127.       wrong places. If this happens, use the 'Clear errors' item (see
  128.       below) and start again.
  129.  
  130.     The following key bindings are only useful if the TEXTERR option is
  131.     specified for the compiler. If not, they have no effect.
  132.  
  133.     'First error' (bound to F7)
  134.  
  135.       This moves the cursor to the first error report in the file.
  136.  
  137.     'Next error' (bound to F8)
  138.  
  139.       This move the cursor to the next error report.
  140.  
  141.     'Prev error' (bound to SHIFT-F8)
  142.  
  143.       This move the cursor to the previous error report.
  144.  
  145.     'Clear errors' (bound to F9)
  146.  
  147.       This deletes all remaining error reports in the file.
  148.  
  149.   Scripts
  150.  
  151.     Most of the work is done by the ARexx script files. Of these, only
  152.     ReadErr.aed contains commands specific to AmokEd, although it is
  153.     called directly by 'DoOC.rexx'.
  154.  
  155.     'DoOC.rexx'
  156.  
  157.       This script takes two arguments: the name of the file to be
  158.       compiled and the name of the public screen it is to open a console
  159.       window on. It gets additional arguments from three environment
  160.       variables:
  161.  
  162.         OC_NEWSYMFILE - contains either 'YES' or 'NO'.  If 'YES', the
  163.           NEWSYMFILE option is included in the compiler's command line.
  164.         OC_DEBUG -  contains either 'YES' or 'NO'.  If 'YES', the DEBUG
  165.           option is included in the compiler's command line.
  166.         OC_ARGS - contains any other options to be included in the
  167.           compiler's command line.
  168.  
  169.       It is the responsibility of the editor to create and set these
  170.       environment variables.
  171.  
  172.       The script will open a console window for the compiler's IO and set
  173.       the stack. If the compiler returns any code other than 0, it calls
  174.       'ReadErr.aed' to insert error reports in the module's source code.
  175.  
  176.     'DoOL.rexx'
  177.  
  178.       This script takes two arguments: the name of the module that is the
  179.       program's entry point, and the name of the public screen it is to
  180.       open a console window on.  It gets additional arguments from an
  181.       environment variable:
  182.  
  183.         OL_ARGS - contains any options to be included in the pre-linker's
  184.           command line.
  185.  
  186.       It is the responsibility of the editor to create and set these
  187.       environment variables.
  188.  
  189.       The script will open a console window for the pre-linker's IO and
  190.       set the stack.
  191.  
  192.     'DoLink.rexx'
  193.  
  194.       This script takes two arguments: the name of the module that is the
  195.       program's entry point, and the name of the public screen it is to
  196.       open a console window on.  It gets additional arguments from an
  197.       environment variable:
  198.  
  199.         LINK_ARGS - contains any options to be included in the linker's
  200.           command line.
  201.  
  202.       It is the responsibility of the editor to create and set these
  203.       environment variables.
  204.  
  205.       The script will open a console window for the linker's IO and set
  206.       the stack.
  207.  
  208.     'ReadErr.aed'
  209.  
  210.       This script takes no arguments. It is the only one that contains
  211.       any AmokEd-specific commands (apart from 'Oberon-A.aedrc'). These
  212.       are concentrated in two areas: one to locate the name of the
  213.       module, and one to insert the error reports in the file. The rest
  214.       of the script is pure ARexx.
  215.  
  216.       The script reads the first four bytes of the error file. If it
  217.       finds the 'OAER' tag, it assumes the error file is in binary format
  218.       and calls OEL to process the errors. The output of OEL is
  219.       redirected to a temporary file, which is displayed in a new window.
  220.  
  221.       If there is no tag, it is assumed that the error file is in human-
  222.       readable format as produced by the compiler's TEXTERR option. The
  223.       script opens the error file skips the first four lines (the
  224.       header). It then parses the rest of the file one line at a time,
  225.       extracting the line, column, and error numbers and storing them in
  226.       a stem variable.
  227.  
  228.       For each error, a line is inserted in the source immediately after
  229.       the line in which it occurred. It processes the entries in reverse
  230.       order so that the inserted lines don't confuse matters.
  231.  
  232.